home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Misc Servers / Zope.exe / APIHELPTOPIC.PY < prev    next >
Encoding:
Python Source  |  2000-06-15  |  9.3 KB  |  276 lines
  1. ##############################################################################
  2. # 
  3. # Zope Public License (ZPL) Version 1.0
  4. # -------------------------------------
  5. # 
  6. # Copyright (c) Digital Creations.  All rights reserved.
  7. # 
  8. # This license has been certified as Open Source(tm).
  9. # 
  10. # Redistribution and use in source and binary forms, with or without
  11. # modification, are permitted provided that the following conditions are
  12. # met:
  13. # 
  14. # 1. Redistributions in source code must retain the above copyright
  15. #    notice, this list of conditions, and the following disclaimer.
  16. # 
  17. # 2. Redistributions in binary form must reproduce the above copyright
  18. #    notice, this list of conditions, and the following disclaimer in
  19. #    the documentation and/or other materials provided with the
  20. #    distribution.
  21. # 
  22. # 3. Digital Creations requests that attribution be given to Zope
  23. #    in any manner possible. Zope includes a "Powered by Zope"
  24. #    button that is installed by default. While it is not a license
  25. #    violation to remove this button, it is requested that the
  26. #    attribution remain. A significant investment has been put
  27. #    into Zope, and this effort will continue if the Zope community
  28. #    continues to grow. This is one way to assure that growth.
  29. # 
  30. # 4. All advertising materials and documentation mentioning
  31. #    features derived from or use of this software must display
  32. #    the following acknowledgement:
  33. # 
  34. #      "This product includes software developed by Digital Creations
  35. #      for use in the Z Object Publishing Environment
  36. #      (http://www.zope.org/)."
  37. # 
  38. #    In the event that the product being advertised includes an
  39. #    intact Zope distribution (with copyright and license included)
  40. #    then this clause is waived.
  41. # 
  42. # 5. Names associated with Zope or Digital Creations must not be used to
  43. #    endorse or promote products derived from this software without
  44. #    prior written permission from Digital Creations.
  45. # 
  46. # 6. Modified redistributions of any form whatsoever must retain
  47. #    the following acknowledgment:
  48. # 
  49. #      "This product includes software developed by Digital Creations
  50. #      for use in the Z Object Publishing Environment
  51. #      (http://www.zope.org/)."
  52. # 
  53. #    Intact (re-)distributions of any official Zope release do not
  54. #    require an external acknowledgement.
  55. # 
  56. # 7. Modifications are encouraged but must be packaged separately as
  57. #    patches to official Zope releases.  Distributions that do not
  58. #    clearly separate the patches from the original work must be clearly
  59. #    labeled as unofficial distributions.  Modifications which do not
  60. #    carry the name Zope may be packaged in any form, as long as they
  61. #    conform to all of the clauses above.
  62. # 
  63. # 
  64. # Disclaimer
  65. # 
  66. #   THIS SOFTWARE IS PROVIDED BY DIGITAL CREATIONS ``AS IS'' AND ANY
  67. #   EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  68. #   IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  69. #   PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL DIGITAL CREATIONS OR ITS
  70. #   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  71. #   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  72. #   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  73. #   USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  74. #   ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  75. #   OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  76. #   OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  77. #   SUCH DAMAGE.
  78. # 
  79. # 
  80. # This software consists of contributions made by Digital Creations and
  81. # many individuals on behalf of Digital Creations.  Specific
  82. # attributions are listed in the accompanying credits file.
  83. # 
  84. ##############################################################################
  85. """
  86. API documentation help topics
  87. """
  88.  
  89. import types
  90. import string
  91. import HelpTopic
  92. from Globals import HTMLFile, Persistent
  93.  
  94. class APIHelpTopic(HelpTopic.HelpTopic):
  95.     """
  96.     Provides API documentation.
  97.     """
  98.  
  99.     isAPIHelpTopic=1
  100.     
  101.     def __init__(self, id, title, file):
  102.         self.id=id
  103.         self.title=title
  104.         dict={}
  105.         execfile(file, dict)
  106.         self.doc=dict.get('__doc__','')
  107.  
  108.         self.apis=[]
  109.         for v in dict.values():
  110.             if type(v)==types.ClassType:
  111.                 self.apis.append(APIDoc(v))
  112.  
  113.         # try to get title from first non-blank line
  114.         # of module docstring
  115.         if not self.title:
  116.             lines=string.split(self.doc,'\n')
  117.             while 1:
  118.                 line=string.strip(lines[0])
  119.                 if line:
  120.                     self.title=line
  121.                     break
  122.                 lines.pop(0)
  123.                 if not lines:
  124.                     break
  125.         # otherwise get title from first class name
  126.         if not self.title:
  127.             self.title=self.apis[0].name
  128.  
  129.     index_html=HTMLFile('APIHelpView', globals())
  130.  
  131.     def SearchableText(self):
  132.         "The full text of the Help Topic, for indexing purposes"
  133.         text="%s %s" % (self.title, self.doc)
  134.         for api in self.apis:
  135.             text="%s %s %s" % (text, api.SearchableText())
  136.         return text
  137.  
  138.       
  139. class APIDoc(Persistent):
  140.     """
  141.     Describes an API.
  142.     """
  143.  
  144.     extends=()
  145.  
  146.     def __init__(self, klass):
  147.         # Creates an APIDoc instance given a python class.
  148.         # the class describes the API; it contains
  149.         # methods, arguments and doc strings.
  150.         # 
  151.         # The name of the API is deduced from the name
  152.         # of the class.
  153.         #
  154.         # The base APIs are deduced from the __extends__
  155.         # attribute.
  156.         
  157.         self.name=klass.__name__ 
  158.         self.doc=trim_doc_string(klass.__doc__)
  159.  
  160.         # inheritence information
  161.         if hasattr(klass,'__extends__'):
  162.             self.extends=[]
  163.             for base in klass.__extends__:
  164.                 names=string.split(base, '.')
  165.                 url="%s/Help/%s.py#%s" % (names[0], names[1], names[2])
  166.                 self.extends.append((names[2], url))
  167.  
  168.         # constructor information
  169.         if hasattr(klass, '__constructor__'):
  170.             self.constructor=MethodDoc(klass.__constructor__)
  171.         
  172.         # Get info on methods and attributes, ignore special items
  173.         self.attributes=[]
  174.         self.methods=[]
  175.         for k,v in klass.__dict__.items():
  176.             if k not in ('__extends__', '__doc__', '__constructor__'):
  177.                 if type(v)==types.FunctionType:
  178.                     self.methods.append(MethodDoc(v))
  179.                 else:
  180.                     self.attributes.append(AttributeDoc(k, v))
  181.         
  182.     def SearchableText(self):
  183.         """
  184.         The full text of the API, for indexing purposes.
  185.         """
  186.         text="%s %s" % (self.name, self.doc)
  187.         for attribute in self.attributes:
  188.             text="%s %s" % (text, attribute.name)
  189.         for method in self.methods:
  190.             text="%s %s %s" % (text, method.name, method.doc)
  191.         return text
  192.         
  193.     view=HTMLFile('APIView', globals())
  194.     
  195.     
  196. class AttributeDoc(Persistent):
  197.     """
  198.     Describes an attribute of an API.
  199.     """
  200.     
  201.     def __init__(self, name, value):
  202.         self.name=name
  203.         self.value=value
  204.  
  205.     view=HTMLFile('attributeView', globals())
  206.  
  207.  
  208. class MethodDoc(Persistent):
  209.     """
  210.     Describes a method of an API.
  211.     
  212.     required - a sequence of required arguments 
  213.     optional - a sequence of tuples (name, default value)
  214.     varargs - the name of the variable argument or None
  215.     kwargs - the name of the kw argument or None
  216.     """
  217.     
  218.     varargs=None
  219.     kwargs=None
  220.     
  221.     def __init__(self, func):
  222.         if hasattr(func, 'im_func'):
  223.             func=func.im_func
  224.  
  225.         self.name=func.__name__
  226.         self.doc=trim_doc_string(func.__doc__)
  227.         
  228.         # figure out the method arguments
  229.         # mostly stolen from pythondoc
  230.         CO_VARARGS = 4
  231.         CO_VARKEYWORDS = 8
  232.         names = func.func_code.co_varnames
  233.         nrargs = func.func_code.co_argcount
  234.         if func.func_defaults:
  235.             nrdefaults = len(func.func_defaults)
  236.         else:
  237.             nrdefaults = 0
  238.         self.required = names[:nrargs-nrdefaults]
  239.         if func.func_defaults:
  240.             self.optional = tuple(map(None, names[nrargs-nrdefaults:nrargs],
  241.                                  func.func_defaults))
  242.         else:
  243.             self.optional = ()
  244.         varargs = []
  245.         ix = nrargs
  246.         if func.func_code.co_flags & CO_VARARGS:
  247.             self.varargs=names[ix]
  248.             ix = ix+1
  249.         if func.func_code.co_flags & CO_VARKEYWORDS:
  250.             self.kwargs=names[ix]
  251.  
  252.     view=HTMLFile('methodView', globals())
  253.  
  254.  
  255. def trim_doc_string(text):
  256.     """
  257.     Trims a doc string to make it format
  258.     correctly with structured text.
  259.     """
  260.     text=string.strip(text)
  261.     text=string.replace(text, '\r\n', '\n')
  262.     lines=string.split(text, '\n')
  263.     nlines=[lines[0]]
  264.     if len(lines) > 1:
  265.         min_indent=None
  266.         for line in lines[1:]:
  267.             indent=len(line) - len(string.lstrip(line))
  268.             if indent < min_indent or min_indent is None:
  269.                 min_indent=indent   
  270.         for line in lines[1:]:
  271.             nlines.append(line[min_indent:])
  272.     return string.join(nlines, '\n')
  273.     
  274.     
  275.     
  276.